home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / boot / sunprom / sync.h.strip < prev    next >
Text File  |  1989-06-10  |  14KB  |  545 lines
  1. /*
  2.  * sync.h --
  3.  *
  4.  *     Definitions of the synchronization module.
  5.  *     The synchronization module provides locks and condition
  6.  *     variables to other modules, plus a low level binary semaphore 
  7.  *    needed to synchronize with interrupt handlers.
  8.  *
  9.  * Copyright 1986 Regents of the University of California
  10.  * All rights reserved.
  11.  *
  12.  * $Header: /sprite/src/kernel/sync/RCS/sync.h,v 8.11 89/04/06 12:09:40 jhh Exp $ SPRITE (Berkeley)
  13.  */
  14.  
  15. #ifndef _SYNC
  16. #define _SYNC
  17.  
  18. #include "sprite.h"
  19. #include "list.h"
  20.  
  21. #include "mach.h"
  22.  
  23. /*
  24.  * Flags for syncFlags field in the proc table:
  25.  *
  26.  *  SYNC_WAIT_REMOTE            - The process is on a wait list somewhere on
  27.  *                                some host and will block until it gets a
  28.  *                                wakeup message.
  29.  *  SYNC_WAIT_COMPLETE          - The process was doing a remote wait and
  30.  *                                it has received a wakeup message.
  31.  */
  32.  
  33. #define    SYNC_WAIT_COMPLETE    0x1
  34. #define    SYNC_WAIT_REMOTE    0x2
  35.  
  36. /*
  37.  * Definitions of variables for instrumentation.
  38.  */
  39.  
  40. typedef struct Sync_Instrument {
  41.     int numWakeups;        /* number of wakeups performed */
  42.     int numWakeupCalls;        /* number of calls to wakeup */
  43.     int numSpuriousWakeups;    /* number of incorrectly awakened sleeps */
  44.     int numLocks;        /* number of calls to MASTER_LOCK */
  45.     int numUnlocks;        /* number of calls to MASTER_UNLOCK */
  46. } Sync_Instrument;
  47.  
  48. /*
  49.  * This is used inside the Sync_Semaphore and Sync_Lock structures to allow
  50.  * them to be linked into lists. Usually the links field is first in a
  51.  * structure so that the list routines work correctly. The CLEAN_LOCK
  52.  * version of locks do not use the links field and expect the value of
  53.  * the lock to be the first field. The easiest solution is to put the
  54.  * links inside a structure which in turn is inside the locks. The linked
  55.  * list elements are these inner structures, which in turn have a pointer
  56.  * to the lock that contains them.
  57.  */
  58. typedef struct Sync_ListInfo {
  59.     List_Links    links;        /* used to link into lists */
  60.     Address    lock;        /* ptr at outer structure that contains this
  61.                  * structure */
  62. } Sync_ListInfo;
  63.  
  64. /*
  65.  * Classes of locks. The "class" field of both locks and semaphores is 
  66.  * at the same offset within the structures. This allows routines to determine
  67.  * the class of a parameter.
  68.  */
  69. typedef enum Sync_LockClass {
  70.     SYNC_SEMAPHORE,            
  71.     SYNC_LOCK
  72. } Sync_LockClass;
  73.  
  74. /*
  75.  *  Maximum types of locks. Types are assigned as locks are registered, 
  76.  *  starting at 1. No distiction is made between locks and semaphores when
  77.  *  assigning a type. The type is used as an index into the array of
  78.  *  statistics for that lock type. Unregistered locks have a type of 0,
  79.  *  and the type of the lock that protects the lock registration itself is
  80.  *  -1. We have to treat this lock specially because a lock is registered
  81.  *  after it is locked, and we need to lock the registration lock in order
  82.  *  to register a lock. Hence we can't register the registration lock.
  83.  */
  84.  
  85. #define SYNC_MAX_LOCK_TYPES 50
  86.  
  87. /*
  88.  * Semaphore structure
  89.  */
  90. typedef struct Sync_Semaphore {
  91.     /*
  92.      * The value field must be first.
  93.      */
  94.     int value;                /* value of semaphore */
  95.     int miss;                /* count of misses on lock */
  96.     int    hit;                /* count of lock hits */
  97. } Sync_Semaphore;
  98.  
  99. typedef struct Sync_KernelLock{
  100.     /*
  101.      * The inUse and waiting fields must be first and in this order.
  102.      */
  103.     Boolean inUse;            /* 1 while the lock is busy */
  104.     Boolean waiting;                /* 1 if someone wants the lock */
  105.     int hit;                /* number of times lock is grabbed */
  106. } Sync_KernelLock;
  107.  
  108. #ifdef KERNEL
  109. typedef Sync_KernelLock Sync_Lock;    /* define locks for kernel */
  110. #endif
  111.  
  112.  
  113.  
  114. /*
  115.  * Exported procedures and variables of the sync module.
  116.  */
  117.     
  118. extern Sync_Instrument     sync_Instrument;
  119. extern int sync_BusyWaits;
  120.  
  121. extern     void         Sync_Init();
  122.  
  123. extern     void         Sync_WakeupProcess();
  124. extern     void         Sync_EventWakeup();
  125. extern     void         Sync_WakeWaitingProcess();
  126. extern     void         Sync_UnlockAndSwitch();
  127.  
  128. extern     Boolean     Sync_SlowMasterWait();
  129. extern     Boolean     Sync_SlowWait();
  130. extern     Boolean     Sync_EventWait();
  131. extern     Boolean     Sync_WaitTime();
  132. extern     Boolean     Sync_WaitTimeInTicks();
  133. extern     Boolean     Sync_WaitTimeInterval();
  134.  
  135. extern     Boolean     Sync_ProcWait();
  136. extern     void         Sync_ProcWakeup();
  137. extern     void         Sync_GetWaitToken();
  138. extern     void         Sync_SetWaitToken();
  139. extern     ReturnStatus     Sync_RemoteNotify();
  140. extern     ReturnStatus     Sync_RemoteNotifyStub();
  141.     
  142. extern     ReturnStatus     Sync_SlowLockStub();
  143. extern     ReturnStatus     Sync_SlowWaitStub();
  144. extern     ReturnStatus     Sync_SlowBroadcastStub();
  145.  
  146. extern     void         Sync_PrintStat();
  147.  
  148. extern    void        Sync_LockStatInit();
  149. extern    void        SyncAddPriorLock();
  150. extern    void        SyncDeleteCurrentLock();
  151. extern     void        SyncMergePriorLocks();
  152. extern    void        Sync_RegisterAnyLock();
  153. extern    void        Sync_CheckoutAnyLock();
  154. extern    void        Sync_PrintLockStats();
  155.  
  156.  
  157.  
  158.  
  159. /*
  160.  *----------------------------------------------------------------------------
  161.  *
  162.  * MASTER_LOCK --
  163.  *
  164.  *    Enter a critical section guarded by a binary semaphore.
  165.  *    This is for use in a multiprocessor environment
  166.  *    within the synchronization module, and in other
  167.  *    modules that interact with interrupt-time routines.
  168.  *    (All other synchronization should be done with Monitors.)
  169.  *    
  170.  *    Interrupts are disabled on the local processor to prevent
  171.  *    a preemptive context switch.  The semaphore is checked
  172.  *    with a Mach_TestAndSet atomic operation in a busy wait
  173.  *    to prevent races with other processors.
  174.  *
  175.  *
  176.  * For uniprocessor debugging, panic when the lock is held (otherwise
  177.  * we get an infinite loop).
  178.  *
  179.  * Results:
  180.  *     None.
  181.  *
  182.  * Side effects:
  183.  *    The semaphore has its value set from 0 to 1.
  184.  *    Interrupts are disabled.
  185.  *
  186.  *----------------------------------------------------------------------------
  187.  */
  188. #define MASTER_LOCK(semaphore) 
  189.  
  190.  
  191.  
  192. /*
  193.  *----------------------------------------------------------------------------
  194.  *
  195.  * MASTER_UNLOCK --
  196.  *
  197.  *    Leave a critical section guarded by a binary semaphore.  This is for
  198.  *    use in a multiprocessor environment.  Interrupts are enabled and the
  199.  *    semaphore value is reset to 0 to allow other processors entry into
  200.  *    the critical section.
  201.  *
  202.  * Results:
  203.  *     None.
  204.  *
  205.  * Side effects:
  206.  *    The semaphore has its value reset to 0.
  207.  *    Interrupts are enabled.
  208.  *
  209.  *----------------------------------------------------------------------------
  210.  */
  211.  
  212. #define MASTER_UNLOCK(semaphore) 
  213.  
  214. /* 
  215.  * Condition variables can be used in critical sections guarded by
  216.  * MASTER_LOCK and MASTER_UNLOCK.  Sync_MasterWait and
  217.  * Sync_MasterBroadcast are the analogues of Sync_Wait and
  218.  * Sync_Broadcast.
  219.  */
  220.  
  221. /*
  222.  *----------------------------------------------------------------------
  223.  *
  224.  * Sync_MasterWait --
  225.  *
  226.  *    Wait on an event with a master lock held.
  227.  *    This has the same semantics as Sync_Wait except
  228.  *    that the lock release when the process sleeps is
  229.  *    a master lock.
  230.  *
  231.  * Results:
  232.  *    None.
  233.  *
  234.  * Side effects:
  235.  *    The process gets descheduled, the master lock gets released
  236.  *    and then reacquired after the condition is notified.
  237.  *
  238.  *----------------------------------------------------------------------
  239.  */
  240.  
  241. #define Sync_MasterWait(conditionPtr, mutexPtr, wakeIfSignal) 
  242.  
  243. /*
  244.  *----------------------------------------------------------------------
  245.  *
  246.  * Sync_MasterBroadcast --
  247.  *
  248.  *    Notify an event, like Sync_Broadcast except it
  249.  *    should be used with a master lock held because of the
  250.  *    check on conditionPtr->waiting.
  251.  *
  252.  *    (This could verify that a master lock is held.)
  253.  *
  254.  * Results:
  255.  *    None.
  256.  *
  257.  * Side effects:
  258.  *    Notify all processes waiting on the event.
  259.  *
  260.  *----------------------------------------------------------------------
  261.  */
  262.  
  263. #define Sync_MasterBroadcast(conditionPtr) 
  264.  
  265.  
  266. /*
  267.  *----------------------------------------------------------------------
  268.  *
  269.  * UNLOCK_AND_SWITCH --
  270.  *
  271.  *    Macro to call the internal routine to release the monitor lock and
  272.  *    then context switch.
  273.  *
  274.  * Results:
  275.  *    None.
  276.  *
  277.  * Side effects:
  278.  *    Lock released and process context switched.
  279.  *
  280.  *----------------------------------------------------------------------
  281.  */
  282.  
  283. #define UNLOCK_MONITOR_AND_SWITCH(state) Sync_UnlockAndSwitch(LOCKPTR, state)
  284.  
  285. /*
  286.  *    The initialization routines are used to initialize a semaphore.
  287.  *    The name parameter is the name of the semaphore and is used to
  288.  *    distinguish between types of locks. If you want the statistics
  289.  *    (hit, miss, etc) for two semaphores to be shared then give them the
  290.  *    same name. An example might be locks around file handles, where it
  291.  *    makes more sense to have the statistics for all the locks as a whole,
  292.  *    rather than just one lock. Also beware that no distinction is made
  293.  *    between locks and semaphores when determining types -- if they have
  294.  *    the same name they have the same type.
  295.  *       Sync_SemClear should be called when a semaphore is being deallocated
  296.  *    and will be no longer used. Currently all this routine does is to
  297.  *    take the statistics associated with the semaphore and merge them in
  298.  *    with those for the type as a whole.
  299.  */
  300.  
  301. /*
  302.  *----------------------------------------------------------------------
  303.  *
  304.  * Sync_SemRegister --
  305.  *
  306.  * Obsolete.
  307.  *
  308.  *----------------------------------------------------------------------
  309.  */
  310. #define Sync_SemRegister Sync_LockRegister
  311.  
  312. /* 
  313.  *----------------------------------------------------------------------
  314.  *
  315.  * Sync_SemClear
  316.  * 
  317.  * Obsolete.
  318.  *
  319.  *----------------------------------------------------------------------
  320.  */
  321. #define Sync_SemClear Sync_LockClear
  322.  
  323.  
  324. /*
  325.  *----------------------------------------------------------------------
  326.  *
  327.  * Sync_SemInitStatic --
  328.  *
  329.  *    Initializes the fields of a semaphore in an initialization statement.
  330.  *    Ex:
  331.  *        static Sync_Semaphore foo = Sync_SemInitStatic("foo");
  332.  *
  333.  * Results:
  334.  *    None.
  335.  *
  336.  * Side effects:
  337.  *    None.
  338.  *
  339.  *----------------------------------------------------------------------
  340.  */
  341.  
  342.  
  343. #define Sync_SemInitStatic(name) \
  344.     {0,0,0}
  345.  
  346.  
  347. /*
  348.  *----------------------------------------------------------------------
  349.  *
  350.  * Sync_SemInitDynamic --
  351.  *
  352.  *    Initializes the fields of a semaphore during program execution.
  353.  *    Ex:
  354.  *        Sync_SemInitDynamic(foo,"foo");
  355.  *
  356.  * Results:
  357.  *    None.
  358.  *
  359.  * Side effects:
  360.  *    None.
  361.  *
  362.  *----------------------------------------------------------------------
  363.  */
  364.  
  365.  
  366. #define Sync_SemInitDynamic(sem,semName) \
  367.     { \
  368.     (sem)->value = (sem)->miss = 0;  \
  369.     (sem)->hit = 0; \
  370.     }
  371.  
  372.  
  373. /*
  374.  *----------------------------------------------------------------------
  375.  *
  376.  * Sync_LockInitStatic --
  377.  *
  378.  *    Initializes the fields of a lock in an initialization statement.
  379.  *    Ex:
  380.  *        static Sync_Lock foo = Sync_LockInitStatic("foo");
  381.  *
  382.  * Results:
  383.  *    None.
  384.  *
  385.  * Side effects:
  386.  *    None.
  387.  *
  388.  *----------------------------------------------------------------------
  389.  */
  390.  
  391. #define Sync_LockInitStatic(name) {0,0}
  392.  
  393.  
  394. /*
  395.  *----------------------------------------------------------------------
  396.  *
  397.  * Sync_LockInitDynamic --
  398.  *
  399.  *    Initializes the fields of a lock during program execution.
  400.  *    Ex:
  401.  *        Sync_LockInitDynamic(foo,"foo");
  402.  *
  403.  * Results:
  404.  *    None.
  405.  *
  406.  * Side effects:
  407.  *    None.
  408.  *
  409.  *----------------------------------------------------------------------
  410.  */
  411.  
  412.  
  413. #define Sync_LockInitDynamic(lock, name) {(lock)->inUse = (lock)->waiting = 0;}
  414.  
  415.  
  416. /*
  417.  *----------------------------------------------------------------------
  418.  *
  419.  * Sync_IsRegistered --
  420.  *
  421.  *    Returns true if a lock or semaphore has already been registered. If
  422.  *    LOCKREG is not defined then this macro always returns FALSE.
  423.  *
  424.  * Results:
  425.  *    TRUE if lock or semaphore registered.
  426.  *
  427.  * Side effects:
  428.  *    None.
  429.  *
  430.  *----------------------------------------------------------------------
  431.  */
  432. #define Sync_IsRegistered(lock) FALSE
  433.  
  434.  
  435. /*
  436.  *----------------------------------------------------------------------
  437.  *
  438.  * Sync_LockRegister --
  439.  *
  440.  *    Used to add a lock to the registration database.
  441.  *    If LOCKREG is not defined then this macro does nothing.
  442.  *
  443.  * Results:
  444.  *    None.
  445.  *
  446.  * Side effects:
  447.  *    The lock is registered.
  448.  *
  449.  *----------------------------------------------------------------------
  450.  */
  451.  
  452. #define Sync_LockRegister(sem) {}
  453.  
  454.  
  455.  
  456.  
  457. /*
  458.  *----------------------------------------------------------------------
  459.  *
  460.  * Sync_LockClear --
  461.  *
  462.  *    Used to clear and deregister a lock before it is freed.
  463.  *    If LOCKREG is not defined then this macro does nothing.
  464.  *
  465.  * Results:
  466.  *    None.
  467.  *
  468.  * Side effects:
  469.  *    The lock is deregistered.
  470.  *
  471.  *----------------------------------------------------------------------
  472.  */
  473.  
  474. #define Sync_LockClear(lock) 
  475.  
  476.  
  477. /*
  478.  *----------------------------------------------------------------------
  479.  *
  480.  * SyncAddPrior --
  481.  *
  482.  *    When a lock is grabbed the prior lock must be added to the prior
  483.  *    types for the lock.
  484.  *    This macro does nothing if LOCKDEP is not defined.
  485.  *
  486.  * Results:
  487.  *    None.
  488.  *
  489.  * Side effects:
  490.  *    None.
  491.  *
  492.  *----------------------------------------------------------------------
  493.  */
  494.  
  495.  
  496. #define SyncAddPrior(type, priorCount, priorTypes, lockPtr, pcbPtr)
  497.  
  498.  
  499. /*
  500.  *----------------------------------------------------------------------
  501.  *
  502.  * SyncMergePrior --
  503.  *
  504.  *    When a lock is cleared its statistics must be added to those for
  505.  *    the type as a whole.
  506.  *    This macro does nothing if LOCKDEP is not defined.
  507.  *
  508.  * Results:
  509.  *    None.
  510.  *
  511.  * Side effects:
  512.  *    None.
  513.  *
  514.  *----------------------------------------------------------------------
  515.  */
  516.  
  517.  
  518. #define SyncMergePrior(priorCount, priorTypes, regPtr)
  519.  
  520.  
  521.  
  522. /*
  523.  *----------------------------------------------------------------------
  524.  *
  525.  * SyncDeleteCurrent --
  526.  *
  527.  *    When we unlock a lock we have to delete it from the stack of 
  528.  *    current locks.
  529.  *    If LOCKDEP is not defined then don't do anything.
  530.  *
  531.  * Results:
  532.  *    None.
  533.  *
  534.  * Side effects:
  535.  *    The lock is removed from the lock stack in the current pcb.
  536.  *
  537.  *----------------------------------------------------------------------
  538.  */
  539.  
  540.  
  541. #define SyncDeleteCurrent(lockPtr, pcbPtr) 
  542.  
  543. #endif /* _SYNC */
  544.  
  545.